Print

1.  Introduction

Sitecore V5 offers you a convenient and flexible solution of creating a custom data provider. The Data Provider allows a User to work with Items located in an external database in the same way as if they were located in the Master database. This article describes how to create a custom data provider using XML Web Services and contains a ready-made example with the source code.

2.  Installation Guide

The SOAP Data Provider is distributed as a standard Sitecore package.Thus, to start using it, you should install the package. Please refer to the ' Installing Modules and Packages ' article if you are not familiar with the standard Sitecore Packager tool.

The following steps are required to make this example work:  

1. M ake sure you have the Northwindsample MSSQL database, which is available for any MS SQL installation (except MSDE), installed.
    
2. Install the soapprovider.zip package.
    
3. Modify the web.config file  

The soapprovider.zip package adds the following Items to Sitecore:

1. Templates:
   /system/templates/SoapProvider/SoapCustomers
   id: {2500B3A6-A274-4A55-BBCC-DDD0893F7BDC}  with the fields:
   ContactName :Text
   CompanyName:Text
   Address:Text
   City:Text
    
   /system/templates/SOAPProvider/SOAPParent
   id: {EECADBEE-2E89-4AD9-9260-CA6F1174B4E2} with no fields (this template only serves as a root Item template).
    
2. An Item
   /content/Home/SOAPParent
   This Item in the content tree will serve as a parent for all dynamically provided Items. These Items are shown in the content tree of the Master database, but, in fact, they are located in an external database.
   
3. ‘NorthwindService’ webservice

 

2.1.  Make changes to the web.config file

2.1.1.  Add the <dataProvider ref="dataProviders/soapprovider"/> definition as shown below:

<!-- master -->
<database id="master" singleInstance="true" type="Sitecore.Data.Database, Sitecore.Kernel">
     <param desc="name">$(id)</param>
        <dataProviders hint="list:AddDataProvider" />           
<dataProvider ref="dataProviders/soapprovider"/> 
<dataProvider ref="dataProviders/main" param1="$(id)"/>
        </dataProviders>
    ...
    </database>

2.1.2.  Add the <soapprovider... </soapprovider> definition as shown below:

 

    <dataProviders>
          <main type="Sitecore.Data.DataProviders.$(database)DataProvider, Sitecore.$(database)">
        <param ref="connections/$(1)"/>
          </main>

      <soapprovider type="SOAPProvider.SOAPDataProvider,SOAPProvider">
           <param desc="ServiceURL">path to WebService</param>
         <param desc="parentTemplateID">parent template ID</param>
         <param desc="templateID">item template ID</param>
         <param desc="filter">filter SQL expression</param>
      </soapprovider>
...
    </dataProviders>

Restart the Client and go to the Content Editor. Expand the /content/home/SOAPParent Item in the Master database. You will be able to see all Items provided by the Data Provider:

 

3.  SOAP Data Provider Architecture

A data provider is a custom class which supplies data to Sitecore from external sources.

In this example, the SOAPProvider . SOAPDataProvider class dynamically builds Items based on the data retrieved from Northwind sample MSSQL database and provides them as children of /content/Home/SOAPParent in the scMaster database.

Keep in mind that you work with an external database despite the fact that the Items are shown as if they were in the Master database.

The external database is accessed via the web service.

3.1.  SoapCustomers Template

In Sitecore V5, each Item must be based on a certain template. In our example, the SoapCustomer template with the fields listed below is used:   

• ContactName : Text
• CompanyName : Text
• Address : Text
• City : Text

3.2.  Data Providers

Please refer to the ‘Integrating External Data Sources’ article for detailed information on the integration of external data sources.

A custom data provider should implement methods of the Sitecore.Data.DataProviders base class.

This particular example implements the following methods:  

• GetItemDefinition
• GetItemFields
• GetChildIDs
• GetParentID
• SaveItem  

All these methods are placed in the SOAPProvider.SOAPDataProvider  example class.

3.3.  Passing Parameters to the Constructor

We can pass all necessary parameters to the constructor of the data provider class using the web.config parameters:

   <soapprovider type="SOAPProvider.SOAPDataProvider,SOAPProvider">
     <param desc="ServiceURL">http://localhost/NorthwindService/Northwind.asmx</param>
     <param desc="parentTemplateID">{EECADBEE-2E89-4AD9-9260-CA6F1174B4E2}</param>
     <param desc="templateID">{2500B3A6-A274-4A55-BBCC-DDD0893F7BDC}</param>
     <param desc="filter">Country='germany'</param>
   </soapprovider>

Where: 

• SOAPProvider.SOAPDataProvider  is a type
   
• SOAPProvider  the assembly name
   
• All entries that begin with <param ...> are parameters that you want to pass to the constructor. Here is the corresponding constructor definition: 

3.4.  Web Service

The package contains the NorthwindService web service.

This service supports the following methods:   

• public string[] GetIDList(string filter)
• public DataSet GetItemFields(string id, string[] fieldnames, string filter)
• public string GetItemName(string id, string filter)
• public void Update(string id, string updateString)
• public string GetFieldNames()

These methods are called by SOAPDataProvider to retrieve and update the data.

You need to change the web.config file to configure the web service:  

3.5.  Data Provider at Work

After you install the SQL Data Provider you will see the Items under /content/Home/SOAPParent Item. These are the Items our Data Provider reads from the Northwind database.

Try to change the field values of the Items and save the Item. You will be able to see the newly updated values in the external database.

4.  Download the Sources

Please refer to the Downloads section for the latest version of the SQL Data Provider.